First iteration on option attributes - #1231

Directive attributes & compile-time directive processing

Introduces a new attribute-based declaration system for reStructuredText directives and moves directive processing from the parse phase into the compile phase.

Moving directive processing to a compiler pass is the groundwork that enables upcoming features such as option validation — with directives now declaratively describing their options via attributes, the framework can inspect and validate them centrally instead of each directive doing ad-hoc parsing.

Features

#[Directive] and #[Option] attributes

• New phpDocumentor\Guides\RestructuredText\Directives\Attributes\Directive attribute declares a directive's name and aliases on the class, replacing the abstract getName() / getAliases() methods.
• New repeatable #[Option] attribute (OptionType, default value, description, example) declares the options a directive supports — used for automatic option validation, type coercion, and documentation.

Compile-time directive processing

• New DirectiveNode represents a parsed directive during compilation and is now processed by a dedicated DirectiveProcessPass compiler pass instead of being resolved eagerly by the parser.
• New ReverseNodeTransformer interface, with support in DocumentNodeTraverser, so parent transforms run after their children.
• Directives expose a createNode(DirectiveNode) entry point; a backward-compat process() path (with isUpgraded()) keeps existing directives working while they are migrated.

Upgraded directives

• Migrated to the attribute model: admonitions (attention, caution, danger, error, hint, important, note, tip, warning), version-change directives (versionadded, versionchanged, deprecated), figure, image, include, confval, youtube, and others.
• readOption() / readAllOptions() on BaseDirective now coerce values to the declared OptionType and apply attribute defaults (e.g. youtube width/height/allow/allowfullscreen).
• Admonitions now correctly apply the option-provided CSS class to the rendered node.

Deprecations

• Directives without a #[Directive] attribute now trigger a deprecation when their name is resolved, pointing to documentation on migrating custom directives.

Notes

• Includes a base-line merge of update-security-issues and a dependency bump.
• This is a first iteration; remaining built-in directives will be migrated to the attribute/compile-time model in follow-ups.